.\" Copyright (c) 2008 Joseph Koshy.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" This software is provided by Joseph Koshy ``as is'' and
.\" any express or implied warranties, including, but not limited to, the
.\" implied warranties of merchantability and fitness for a particular purpose
.\" are disclaimed.  in no event shall Joseph Koshy be liable
.\" for any direct, indirect, incidental, special, exemplary, or consequential
.\" damages (including, but not limited to, procurement of substitute goods
.\" or services; loss of use, data, or profits; or business interruption)
.\" however caused and on any theory of liability, whether in contract, strict
.\" liability, or tort (including negligence or otherwise) arising in any way
.\" out of the use of this software, even if advised of the possibility of
.\" such damage.
.\"
.\" $Id$
.\"
.Dd August 31, 2008
.Os
.Dt ELFCOPY 1
.Sh NAME
.Nm elfcopy
.Nd copy and translate object files
.Sh SYNOPSIS
.Nm
.Op Fl -add-section Ar sectionname Ns = Ns Ar filename
.Op Fl -discard-all
.Op Fl -discard-locals
.Op Fl -help
.Op Fl -input-target= Ns Ar objformat
.Op Fl -keep-symbol= Ns Ar symbolname
.Op Fl -localize-symbol= Ns Ar symbolname
.Op Fl -only-keep-debug
.Op Fl -only-section= Ns Ar sectionname
.Op Fl -output-target= Ns Ar objformat
.Op Fl -preserve-dates
.Op Fl -remove-section= Ns Ar sectionname
.Op Fl -rename-section Ar oldname Ns = Ns Ar newname Ns Op Ar ,flags
.Op Fl -set-section-flags Ar sectionname Ns = Ns Ar flags
.Op Fl -strip-all
.Op Fl -strip-debug
.Op Fl -strip-symbol= Ns Ar symbolname
.Op Fl -strip-unneeded
.Op Fl -version
.Op Fl -weaken-symbol= Ns Ar symbolname
.Op Fl I Ar objformat
.Op Fl K Ar symbolname
.Op Fl L Ar symbolname
.Op Fl N Ar symbolname
.Op Fl O Ar objformat
.Op Fl R Ar sectionname
.Op Fl S
.Op Fl V
.Op Fl X
.Op Fl d
.Op Fl h
.Op Fl g
.Op Fl j Ar sectionname
.Op Fl p
.Op Fl x
.Ar infile
.Op Ar outfile
.Sh DESCRIPTION
The
.Nm
utility copies the content of the ELF object named by argument
.Ar infile
to that named by argument
.Ar outfile ,
transforming it according to the command line options specified.
If argument
.Ar outfile
is not specified,
.Nm
will create a temporary file and will subsequently rename it as
.Ar infile .
.Pp
The
.Nm
utility supports the following options:
.Bl -tag -width indent
.It Fl -add-section Ar sectionname Ns = Ns Ar filename
Add a new section to the output file with name
.Ar sectionname .
The contents of the section are taken from the file named by
argument
.Ar filename .
The size of the section will be the number of bytes in file
.Ar filename .
.It Fl -discard-all
Do not copy non-global symbols to the output.
.It Fl -discard-locals
Do not copy compiler generated local symbols to the output.
.It Fl -input-target= Ns Ar objformat
This option is accepted for compatibility with GNU
.Xr objcopy 1 ,
but is ignored.
.It Fl -keep-symbol= Ns Ar symbolname
Copy the symbol named by argument
.Ar symbolname
to the output.
.It Fl -localize-symbol= Ns Ar symbolname
Make the symbol named by argument
.Ar symbolname
local to the output file.
.It Fl -only-keep-debug
Copy only debugging information to the output file.
.It Fl -only-section= Ns Ar sectionname
Copy only the section named by argument
.Ar sectionname
to the output.
.It Fl -output-target= Ns Ar objformat
Write the output file using the object format specified in argument
.Ar objformat .
.It Fl -preserve-dates
Set the access and modification times of the output file to the
same as those of the input.
.It Fl -remove-section= Ns Ar sectionname
Remove any section with name
.Ar sectionname
from the output file.
.It Fl -rename-section Ar oldname Ns = Ns Ar newname Ns Op Ar ,flags
Rename the section named by argument
.Ar oldname
to
.Ar newname ,
optionally changing the sections flags to that specified by argument
.Ar flags .
Allowed values for the argument
.Ar flags
are as for option
.Fl -set-section-flags
below.
.It Fl -set-section-flags Ar sectionname Ns = Ns Ar flags
Set the flags for the section named by argument
.Ar sectionname
to those specified by argument
.Ar flags .
Argument
.Ar flags
is a comma separated list of the following flag names:
.Bl -tag -width "readonly" -compact
.It alloc
The section occupies space in the output file.
.It code
The section contains machine instructions.
.It contents
.\" XXX what does this flag mean?
.It data
The section contains writeable data.
.It debug
The section holds debugging information.
.It load
The section is loadable.
.It noload
The section should not be loaded into memory.
.It readonly
The section is not writable.
.It rom
The section contains ROM'able contents.
.It share
.\" XXX what does this section flag mean?
.El
.It Fl -strip-all
Do not copy symbol and relocation information to the target file.
.It Fl -strip-debug
Do not copy debugging information to the target file.
.It Fl -strip-symbol= Ns Ar symbolname
Do not copy the symbol named by argument
.Ar symbolname
to the output.
.It Fl -strip-unneeded
Do not copy symbols that are not needed for relocation processing.
.It Fl -version
Print a version identifier and exit.
.It Fl -weaken-symbol= Ns Ar symbolname
Mark the symbol named by argument
.Ar symbolname
as weak in the output.
.It Fl I Ar objformat
Identical to option
.Fl -input-target= Ns Ar format .
.It Fl K Ar symbolname
Identical to option
.Fl -keep-symbol= Ns Ar symbolname .
.It Fl L Ar symbolname
Identical to option
.Fl -localize-symbol= Ns Ar symbolname .
.It Fl N Ar symbolname
Identical to option
.Fl -strip-symbol= Ns Ar symbolname .
.It Fl R Ar sectionname
Identical to option
.Fl -remove-section= Ns Ar sectionname .
.It Fl S
Identical to option
.Fl -strip-all .
.It Fl V
Identical to option
.Fl -version .
.It Fl W Ar symbolname
Identical to option
.Fl -weaken-symbol= Ns symbolname .
.It Fl X
Identical to option
.Fl -discard-locals .
.It Fl d
Identical to option
.Fl -strip-debug .
.It Fl g
Identical to option
.Fl -strip-debug .
.It Fl j Ar sectionname
Identical to option
.Fl -only-section= Ns Ar sectionname .
.It Fl p
Identical to option
.Fl -preserve-dates .
.It Fl x
Identical to option
.Fl -discard-all .
.El
.Sh DIAGNOSTICS
.Ex -std
.Sh SEE ALSO
.Xr ar 1 ,
.Xr ld 1 ,
.Xr elf 3 ,
.Xr ar 5 ,
.Xr elf 5
.Sh HISTORY
.Nm
has been implemented by
.An "Kai Wang" Aq kaiwang27@users.sourceforge.net .
